Short: AmigaShell PIPE command
Type: util/shell
Uploader: mlelstv@serpens.rhein.de
Author: mlelstv@serpens.rhein.de

One of the nice features of a UNIX shell is the possibility
to chain several commands together so that the output of
one command is passed as the input of the next command.

With the AmigaShell you have to launch each task individually
in the background with the RUN command and proper redirection
to individual PIPEs (as AmigaDOS PIPEs need a unique name, there
are no 'unnamed' pipes as in UNIX).

An undocumented feature of the AmigaShell since AmigaOS2.0 is
the possibility to pass chains of commands on a single command
line to an external command for evaluation. This is done by
setting the local shell variables _pchar and _mchar to some
strings. Whenever one of these strings appears on the command
line the shell will pass the total commandline to the program
C:PIPE (or a resident PIPE command) for further evaluation.
The shell will not execute the commands in the pipe itself.

Andy Finkel (author of the AmigaShell) did publish such a C:PIPE
program some time ago. Unfortunately this program has a couple
of bugs.

Here is my version of C:PIPE with hopefully less bugs.

----------------------------------------------------------------------------
How to use install PIPE:

Copy PIPE to your C: directory, you should preserve the protection
flags or set the p bit manually with the PROTECT command. This
ensures that you can load the program into the shell's resident
list.

In your shell-startup you insert the commands

set _pchar "|"
set _mchar "||"

to activate the PIPE command. _pchar refers to the actual pipe chaining,
_mchar is used to group commands that are executed sequentially (and whose
output can be passed into another command). You can use other strings than
"|" or "||" but you should be careful not to conflict with common strings
used as parameters. You cannot use ";" as this starts a comment that is
removed by the AmigaShell. Of course, you cannot use "<" or ">" either.

Now make sure that you have mounted the PIPE: device.

----------------------------------------------------------------------------
How to use PIPE:

When you have set up the shell-startup you can run a new shell. Something
like

LIST | MORE

will now show a directory listing page by page. Users of the pbmplus
package will like the possibility to

djpeg mypic.jpg | pnmscale -xysize 320 200 | ppmtoilbm -ham >mypic.iff

There are some commands that do not use the standard input and output
but want explicit file names instead. One prominent example is the C:SORT
command. It would be nice to use

LIST | SORT | MORE

to get a sorted directory listing, but since SORT does not read its
input this is not possible. As a solution the PIPE command will replace
the arguments IN: and OUT: with the actual AmigaDOS PIPE: names used. So

LIST | SORT FROM IN: TO OUT: | MORE

will do what we want. The argument replacement occurs only once for each
command (the last parameter named IN: or OUT: is replaced) since you can
only open or create a pipe once.

----------------------------------------------------------------------------
I/O-Redirection:

The AmigaShell just supports one input and one output redirection on the
command line. The redirection is used for the complete pipeline, independent
on where the redirection is placed on the command line. The input redirection
affects the _first_ command on the line, the output redirection affects the
last command on the line.

Aborts:

When you run a pipe then a CTRL-C/D/E/F will be send to the _last_ command
in the pipe. When this command stops it closes its input pipe and the
program that writes to that pipe should see a write error and stop.
Unfortunately there are some programs that ignore write errors and will
continue to run. Their output is discarded by the PIPE: device, but they
may take some time to complete. If necessary you can use the C:BREAK command
to send them individual break signals.

Queue-Handler:

The AmigaDOS PIPE: device (at least the one in 3.0 and 3.1) has a bug that
will make it loose data whenever a program writes to a pipe with a Write()
call larger than the buffer size of the pipe. There is a replacment queue-
handler from Heinz Wrobel in beta test that fixes this problem.

IN: and OUT:

The command line parser does not look at quoted strings for replacement.
I.e. you should use IN: and OUT: and not "IN:" and "OUT:".

Michael van Elst
